Table of Contents

Previous Section

Creating Arrays

+ array

Returns an empty array. Usually used to create NSMutableArrays. NSArrays created with this method are permanently empty.

		// Most common use

		id mutableArray = [NSMutableArray array];



		// May not be what you want

		id array = [NSArray array];

+ arrayWithObject:

Returns an array containing the single specified object.

+ arrayWithObjects:

Returns an array containing the objects in the argument list. The argument list is a comma-separated list of objects ending with nil.

		id array = [NSMutableArray arrayWithObjects:

			@"Plates", @"Plasticware", @"Napkins", nil];

+ arrayWithArray:

Returns an array containing the contents of a specified array. Usually used to create an NSMutableArray from an immutable NSArray, or vice-versa. For example, the following statement creates an NSMutableArray from a constant NSArray object:

		id mutableArray = [NSMutableArray 

			arrayWithArray:@("A", "B", "C")];

+ arrayWithContentsOfFile:

Returns an array initialized from the contents of a specified file. The specified file can be a full or relative pathname; the file that it names must contain a string representation of an array, such as that produced by the writeToFile:atomically: method. See also description.

- count

Returns the number of objects in the array.

- isEqual:

Returns YES if the specified object is an array and has contents equivalent to the receiver; NO, otherwise. Two arrays have equal contents if they each hold the same number of objects and objects at a given index in each array satisfy the isEqual: test.

- objectAtIndex:

Returns the object located at a specified index. Arrays have a zero-based index. The first object in an array is at index 0, the second is at index 1, and so on. It is an error to specify an index that is out of bounds (greater than or equal to the array's count).

- indexOfObject:

Returns the index of the first object in the array that is equivalent to a specified object, or NSNotFound if an equivalent object isn't found. To determine equality, each element of the array is sent an isEqual: message.

- indexOfObjectIdenticalTo:

Returns the index of the first occurrence of the a specified object, or NSNotFound if the specified object isn't found. To determine equality, the ids of the two objects are compared.

- sortedArrayUsingSelector:

Returns an NSArray that lists the receiver's elements in ascending order, as determined by a specified method. This method is used to sort arrays containing strings and/or numbers. For example, the following code excerpt creates the NSArray sortedArray containing the string "Alice" at index 0, "David" at index 1, and so on:

		id guestArray = @("Suzy", "Alice", "John", "Peggy", 
"David");

		id sortedArray = [guestArray 
sortedArrayUsingSelector:@"compare:"];

When removing objects using NSMutableArray's removeObject... methods, note that the objects are sent a release message as they're removed. Thus, the following can cause an error:

id anObj = [aList objectAtIndex:0];
[aList removeObjectAtIndex:0];
[aList addObject:anObj];	// anObj may already be dealloc'd

- addObject:

Adds a specified object at the end of the receiver. It is an error to specify nil as an argument to this method. You cannot add nil to an array.

- insertObject:atIndex:

Inserts an object at a specified index. If the specified index is already occupied, the objects at that index and beyond are shifted down one slot to make room. The specified index can't be greater than the receiver's count, and the specified object cannot be nil.

Array objects have a zero-based index. The first object in an array is at index 0, the second is at index 1, and so on. You can insert only new objects in ascending order-with no gaps. Once you add two objects, the array's size is 2, so you can insert objects at indexes 0, 1, or 2. Index 3 is illegal and out of bounds.

It is an error to specify nil as an argument to this method. You cannot add nil to an array. It is also an error to specify an index that is greater than the array's count.

- removeObject:

Removes all objects in the array equivalent to a specified object, and moves elements up as necessary to fill any gaps. Equivalency is determined using the isEqual: method. Removed objects are sent release as they're removed.

- removeObjectIdenticalTo:

Removes all occurrences of a specified object and moves elements up as necessary to fill any gaps. Removed objects are sent release as they're removed.

- removeObjectAtIndex:

Removes the object at a specified index and moves all elements beyond the index up one slot to fill the gap. Arrays have a zero-based index. The first object in an array is at index 0, the second is at index 1, and so on. Removed objects are sent release as they're removed.

It is an error to specify an index that is out of bounds (greater than or equal to the array's count).

- removeAllObjects

Empties the receiver of all of its elements. Removed objects are sent release as they're removed.

- setArray:

Empties the receiver of all its elements, then adds the contents of a specified array.

- writeToFile:atomically:

Writes the array's string representation to a specified file using the description method. Returns YES on success and NO on failure. If YES is specified for atomically:, this method attempts to write the file safely so that an existing file with the specified path is not overwritten, and it does not create a new file at the specified path unless the write is successful. The resulting file is suitable for use with arrayWithContentsOfFile:. For example, the following code excerpt creates guestArray with the contents of the specified file, adds a new guest, and saves the changes to the same file:

		id guestArray = [NSMutableArray 
arrayWithContentsOfFile:path];

		[guestArray addObject:newGuest];

		[guestArray writeToFile:path atomically:YES];

- description

Returns a string that represents the contents of the receiver. For example, the following code excerpt produces the string "(Plates, Plasticware, Napkins)":

		id array = [NSMutableArray arrayWithObjects:

			@"Plates", @"Plasticware", @"Napkins", nil];

		id description = [array description];

- componentsJoinedByString:

Returns an NSString created by interposing a specified string between the elements of the receiver's objects. Each element of the array must be a string. If the receiver has no elements, an empty string is returned. See also componentsSeparatedByString: (in NSString and NSMutableString). For example, the following code excerpt creates the NSString dashString with the contents "A-B-C":

		id commaString = @"A, B, C";

		id array = [string 
componentsSeparatedByString:@","];

		id dashString = [array componentsJoinedByString:@"-
"];

Table of Contents Next Section